TEXT

Note: The Rotate method only applies to text objects that are within the annotation layer, not the dataspace. For text objects in the dataspace, use the ORIENTATION property to rotate the text. Also, the Scale method is not available for text objects. To scale the text, use the FONT_SIZE property.

Return Value

The TEXT function returns a reference to the created text annotation. Use the returned reference to manipulate the annotation after creation by changing properties or calling methods.

Arguments

X

Y

Z

The location where the text will be placed, in data, normal, or device coordinates. If X, Y, and Z are arrays, then an array of TEXT objects will be returned.

String

The text to be displayed. If the string is an array, each item displays on a separate line. You can add mathematical symbols and greek letters using a TeX-like syntax. For details see below.

Format

A string that sets the text color using short tokens. For example, to create red text, you would use the following:

t = TEXT(0.5, 0.5, 'Hello', 'r')

Keywords

Keywords are applied only during the initial creation of the graphic.

DATA

Set this keyword if the input arguments are specified in data coordinates. Setting this keyword inserts the text into the current data space, otherwise the text is added to the annotation layer.

DEVICE

Set this keyword if the input arguments are specified in device coordinates (pixels).

NORMAL

Set this keyword if the input arguments are specified in normalized ( [0, 1] ) coordinates (the default).

RELATIVE

Set this keyword to indicate that the input arguments are specified in normalized [0,1] coordinates, relative to the axis range of the TARGET's dataspace. If the TARGET keyword is not specified, then setting /RELATIVE is the same as setting /NORMAL.

Note: When using /RELATIVE, even though the coordinates are relative to the TARGET's dataspace, the graphic is added to the annotation layer, not to the dataspace.

TARGET

Set this keyword to the graphic object to use if points are specified in data coordinates.

Properties

ALIGNMENT

A floating-point value between 0.0 and 1.0 that indicates the horizontal alignment of the text baseline. An alignment of 0.0 (the default) left-justifies the text at the given position; an alignment of 1.0 right-justifies the text, and an alignment of 0.5 centers the text.

BASELINE

A two- or three-element floating-point vector that sets the direction in which the baseline is to be oriented. Use this property in conjunction with UPDIR to specify the plane on which the text lies.

The following table gives the commonly-used BASELINE values:

Vector	Description
[1.0, 0, 0]	Parallel to +X axis (default)
[0, 1.0, 0]	Parallel to +Y axis
[0, 0, 1.0]	Parallel to +Z axis

CLIP

Set this property to 1 to clip portions of the text that lie outside of the dataspace range, or to 0 to disable clipping. The default is 1. This property is ignored unless the DATA property is set.

COLOR

Set this property to a string or RGB vector that specifies the text color. The default is "black".

FILL_BACKGROUND

A value of 1 fills the area inside the text box.

FILL_COLOR

Set this property to a string or RGB vector that specifies the fill color inside the text box.

FONT_COLOR

Set this property to a string or RGB vector that specifies the text color. The default value is "black".

FONT_NAME

A string specifying the name of the IDL or system font to use for the text string. The default value is "DejaVuSans". The following font names are available on all systems:

"Helvetica"
"Times"
"Courier"
"Symbol"
"Monospace Symbol"
"DejaVuSans"
"DejaVuSymbol"
"Hershey n", where n is the Hershey font number

On Windows platforms, you may also use any other fonts installed on your system.

See Using TrueType Fonts for a list of available characters in the above fonts.

FONT_SIZE

Set this property to an integer or floating-point value giving the font size in points. The default is 9.

FONT_STYLE

An integer or string specifying the font style to be used for the text string. Allowed values are:

Integer	String	Resulting Style
0	"Normal" or "rm"	Default (roman)
1	"Bold" or "bf"	Bold
2	"Italic" or "it"	Italic
3	"Bold italic" or "bi"	Bold italic

HIDE

Set this property to 1 to hide the graphic. Set HIDE to 0 to show the graphic.

NAME

A string that specifies the name of the graphic. The name can be used to retrieve the graphic using the brackets array notation. If NAME is not set then a default name is chosen based on the graphic type.

ONGLASS

Set this property to 1 to display the text on a plane facing the viewer. Set this property to 0 to display the text using the full 3-D orientation of the text object and its parents. The default is ONGLASS=1 for text in a 2-D data space with a non-zero ORIENTATION. The default is ONGLASS=0 for text with ORIENTATION=0, or for text in a 3-D data space.

Note: If ONGLASS is set to 1, then IDL will automatically set the CLIP property to 0, to avoid clipping the text.

ORIENTATION

Set this property to the angle of the text annotation. The angle rotates counterclockwise from the positive x axis. If not supplied, the default value 0 is used.

POSITION

Set this property to a two-element vector that determines the position of the graphic within the window. Coordinates are expressed in normalized units ranging from 0.0 to 1.0. On creation, if the DEVICE keyword is set, the units are given in device units (pixels).

STRING

After the text annotation is created, set this property to a string or an array of strings to change the displayed text. If STRING is an array then each string will be placed on a separate line.

TRANSPARENCY

An integer between 0 and 100 that specifies the percent transparency of the text. The default value is 0.

UPDIR

A two- or three-element floating-point vector describing the vertical direction for the string. The upward direction is the direction defined by a vector pointing from the origin to the point specified.

Use this property in conjunction with BASELINE to specify the plane on which the text lies (the direction specified by UPDIR should be orthogonal to the direction specified by BASELINE).

For example, to have a string to lie in the Y-Z plane pointing downwards and towards you, define BASELINE to be [0, 0, 1.0] (the +Z direction), and UPDIR to be [0, -1.0, 0] (the -Y direction).

UVALUE

Set this property to an IDL variable of any data type.

VERTICAL_ALIGNMENT

A floating-point value between 0.0 and 1.0 that indicates the vertical alignment of the text baseline. An alignment of 0.0 (the default) bottom-justifies the text at the given position; an alignment of 1.0 top-justifies the text.

WINDOW (Get Only)

This property retrieves a reference to the WINDOW object which contains the graphic.

Adding Mathematical Symbols and Greek Letters to the Text String

You can add mathematical symbols and Greek letters to the text string using a TeX-like syntax. To turn on math symbols for a text string (or a portion of a string), you need to surround that region with a pair of "$" characters. The following tables list the letters and symbols you can embed within a text string.

Greek Letters

Binary Operators

Relations and Arrows

Math Miscellaneous

Other Symbols

Accents

Superscripting and Subscripting

Within the $ ... $ sections, use an underscore "_" character to create a subscript, and a caret "^" to create a superscript. If the underscore or caret is followed by a single character, only that character will be subscripted or superscripted. Optionally, you can use curly braces { } to subscript or superscript an entire group of characters. You can also nest superscripts and subscripts (two levels only).

For example:

Changing Fonts and Special Characters

Use the following commands to change fonts or add spacing within the $ ... $ sections of the string:

Command	Description
\bf	Helvetica bold
\it	Helvetica italic
\bi	Helvetica bold italic
\rm	Default font
\t	Add a tab (4 spaces)
\n	Add a carriage return

Miscellaneous Unicode Symbols

You can also use "\U(u₀, u₁,...,u_n)" to insert arbitrary Unicode characters from the DejaVuSans font. Each u_i within the parentheses will be interpreted as a 16-bit hexadecimal Unicode value. For example:

w = WINDOW()

t = TEXT(0.01, 0.05, "$\U(266A,266C) \Pluto's really small \U(266B)$")

The SHOWFONT procedure may be used to display the Unicode characters from the DejaVuSans font.

Note: To include Unicode characters from a font other than DejaVuSans, use the FONT_NAME property to change the font, and then use the "!Z" embedded formatting command instead of "\U".

Note: To include Unicode characters in an EPS or PDF file, use the BITMAP keyword to the Save method. Otherwise the Unicode characters may display incorrectly.

Tips

Math symbols, superscripts, subscripts, and the font commands are only active within the $ ... $ sections of your string. To include a normal "$" character within your string, you should escape it by inserting a backslash in front, like this: "\$".
If a text formatting command is followed by a single space character, that space is ignored. For example, in the string "$A\times B$", the resulting string is "AxB", with no space. Any additional spaces following the symbol will be included in the output.
A fixed-width space may be inserted using "\ " (backslash+space).
The "\sqrt" square root symbol is wide enough to accommodate one character underneath the root. You can use curly braces { } to include a group of characters. For example, you could do "$\sqrt{b^2 - 4ac}$".
The "\overline" symbol is wide enough to accommodate one character underneath the line. You can use curly braces { } to include a group of characters. For example, you could do "$1/7 = 0.\overline{142857}$".
When combining subscripts and superscripts, to ensure that the spacing is correct, it is best to put the longest group of characters last. For example, instead of:

"$A_{ijk}^{2}B$"

You should compose the string this way:

"$A^{2}_{ijk}B$"

Within the $ ... $ sections, the characters \, {, }, ^, and _ are all special control characters. To insert one of these characters into your string, use the backslash as an escape character. For example:

"\\", "\{", "\}", "\^", "\_"

In addition to the above commands, you can also use the embedded formatting commands to control text formatting and position.

Version History

8.0	Introduced
8.1	Added the UVALUE property and the Delete method.
8.2	Added \dagger, \ddagger, \emptyset, \permil, \primeprime, and the Unicode symbols, including the planets. Added Unicode \U support. Added \sqrt{ } support.
8.2.2	Added POSITION property.
8.2.3	Added \overline{ }.
8.3	Added ONGLASS property; added \\| and \perp symbols.
8.4	Added \t and \n commands.
8.5	Added \star symbol.
8.6	Changed default font to DejaVuSans. Added new symbols.
8.6.1	Changed default math font to DejaVuSymbol.

TEXT

Example

Additional Examples

Syntax

Keywords

Properties

Methods

Return Value

Arguments

X

Y

Z

String

Format

Keywords

DATA

DEVICE

NORMAL

RELATIVE

TARGET

Properties

ALIGNMENT

BASELINE

CLIP

COLOR

FILL_BACKGROUND

FILL_COLOR

FONT_COLOR

FONT_NAME

FONT_SIZE

FONT_STYLE

HIDE

NAME

ONGLASS

ORIENTATION

POSITION

STRING

TRANSPARENCY

UPDIR

UVALUE

VERTICAL_ALIGNMENT

WINDOW (Get Only)

Adding Mathematical Symbols and Greek Letters to the Text String

Greek Letters

Binary Operators

Relations and Arrows

Math Miscellaneous

Other Symbols

Accents

Superscripting and Subscripting

Changing Fonts and Special Characters

Miscellaneous Unicode Symbols

Tips

Version History

See Also